Build And Deployment

1. Introduction

2. Project Structure

3. Core Components

4. Architecture Overview

5. Detailed Component Analysis

6. Dependency Analysis

7. Performance Considerations

8. Troubleshooting Guide

9. Conclusion

10. Appendices

This document explains the complete build system and deployment processes for the desktop application. It covers development environment setup for Node.js and Python, the Vite-based frontend build pipeline, electron-builder configuration for cross-platform distribution, and the GitHub Actions CI/CD pipeline for automated testing and releases. It also documents platform-specific build targets, packaging formats, release management procedures, and troubleshooting guidance.

The project is organized into:

• Electron application with React frontend and Electron main/preload processes

• Python backend utilities for contact processing and validation

• GitHub Actions workflows for CI/CD

Diagram sources

• package.json

• vite.config.js

• electron-builder.json

• main.js

• preload.js

• App.jsx

• main.jsx

• requirements.txt

• app.py

• extract_contacts.py

• parse_manual_numbers.py

• release.yml

Section sources

• README.md

• package.json

• vite.config.js

• electron-builder.json

• main.js

• preload.js

• requirements.txt

• app.py

• release.yml

• Electron app entry and window lifecycle

• Vite build configuration for React frontend

• electron-builder configuration for cross-platform packaging

• GitHub Actions release workflow

• Python backend services for contact processing

Key responsibilities:

• Electron main process initializes the app, sets up IPC, and manages the renderer window

• Vite builds the React UI into dist-react

• electron-builder packages the app for Windows, macOS, and Linux with specified targets

• GitHub Actions automates builds and releases on version tags

Section sources

• main.js

• vite.config.js

• electron-builder.json

• release.yml

• app.py

The build and deployment pipeline integrates frontend build, packaging, and release automation:

Diagram sources

• release.yml

• package.json

• vite.config.js

• electron-builder.json

Development Environment Setup#

• Node.js and npm: Required for Electron and Vite

• Python 3.8+: Required for backend utilities

• Google Cloud credentials (for Gmail API)

• Environment variables: Place credentials in a .env file in the electron directory

Recommended commands:

• Install Electron dependencies

• Install Python backend dependencies

• Start development server

Section sources

• README.md

• requirements.txt

• package.json

Vite-Based Frontend Build Process#

• Plugins: React and Tailwind CSS

• Base path configured for relative asset resolution

• Output directory: dist-react

• Development server port: 5173

Optimization strategies:

• Use production build for distribution

• Leverage React plugin for fast refresh in development

• Tailwind CSS for efficient styling

Section sources

• vite.config.js

• eslint.config.js

Electron Main Process and Window Lifecycle#

• Creates a BrowserWindow with context isolation and preload script

• Loads development URL during dev mode or production HTML from dist-react

• Handles errors for failed resource loads

• Manages WhatsApp client lifecycle and cleanup

Section sources

• main.js

• main.js

Preload Script and IPC Bridge#

• Exposes a typed API to the renderer via contextBridge

• Provides methods for Gmail, SMTP, file operations, and WhatsApp integration

• Registers listeners for progress and status events

Section sources

• preload.js

Electron Builder Configuration#

• App ID and included files

• Extra resources for preload and assets

• Platform-specific targets:

  • macOS: dmg

  • Linux: AppImage with category Utility

  • Windows: portable and msi

Section sources

• electron-builder.json

CI/CD Pipeline with GitHub Actions#

• Triggers on version tags and manual dispatch

• Matrix builds for macOS, Ubuntu, and Windows

• Steps:

  • Checkout code

  • Setup Node.js 18 with npm caching

  • Install Electron dependencies

  • Build React app

  • Build distributables per platform

  • Upload artifacts

  • Create GitHub Releases with generated release notes

Artifacts uploaded per platform:

• macOS: .dmg

• Windows: .exe, .zip, .tar.gz

• Linux: .AppImage, .deb, .rpm, .snap

Section sources

• release.yml

Python Backend Utilities#

• Flask API for contact extraction and validation

• CLI utilities for parsing manual numbers and extracting contacts

• Dependencies managed via requirements.txt

Endpoints and capabilities:

• Health check endpoint

• File upload and contact extraction

• Manual number parsing

• Single number validation

Section sources

• app.py

• extract_contacts.py

• parse_manual_numbers.py

• requirements.txt

The build system relies on:

• Electron and Vite for the desktop app

• electron-builder for packaging

• GitHub Actions for automation

• Python libraries for backend utilities

Diagram sources

• vite.config.js

• electron-builder.json

• main.js

• preload.js

• release.yml

Section sources

• package.json

• electron-builder.json

• release.yml

• Use production builds for distribution to minimize bundle size

• Keep preload and main process code minimal and focused

• Optimize asset loading and avoid blocking the UI thread

• Consider lazy-loading heavy components in the future

[No sources needed since this section provides general guidance]

Common build and deployment issues:

• Electron dev server not starting: verify Vite config and port availability

• Packaging failures: confirm electron-builder targets and extra resources paths

• CI failures on tags: ensure semantic version tags and permissions

• Missing icons or assets: verify paths in electron-builder.json

• Python backend errors: check Flask routes and file uploads

Section sources

• main.js

• electron-builder.json

• release.yml

• README.md

The project employs a robust build and deployment pipeline combining Vite for the React frontend, Electron for the desktop runtime, electron-builder for cross-platform packaging, and GitHub Actions for automated releases. Following the documented setup and procedures ensures reliable development, optimized builds, and consistent distribution across Windows, macOS, and Linux.

[No sources needed since this section summarizes without analyzing specific files]

Development Commands#

• Start development: run dev (React dev server + Electron)

• Build React app: run build

• Production start: run prod

• Platform builds: dist:mac, dist:win, dist:linux

• Lint code: run lint

Section sources

• README.md

• package.json

Release Management Procedures#

• Version tagging: use npm version patch/minor/major in electron directory

• Push tags to trigger CI/CD

• Releases are created automatically with artifacts and release notes

Section sources

• README.md

• release.yml

Platform-Specific Targets and Packaging Formats#

• macOS: dmg

• Windows: portable, msi

• Linux: AppImage, deb, rpm, snap

Section sources

• electron-builder.json

• README.md